//
//  TCPConnection.h
//  MailDelivery
//
//  Created by Dante Palacios on 9/24/09.
//  Copyright 2009 Dante Palacios. All rights reserved.
//


/*!
 @header TCPConnection.h
 @abstract The methods listed here may disappear or change their names without prior notice. For more information, contact palacios.dante\@gmail.com.
 */

#import <Foundation/Foundation.h>
#import <Security/Security.h>

/*!
 @enum MailDeliverySecurityLevel
 @discussion Constants the represent the SSL security level.
 @constant MailDeliverySecurityLevelNone Don't use SSL. Authentication may fail with some servers.
 @constant MailDeliverySecurityLevelSSLv3 Indicates to use SSLv3.
 @constant MailDeliverySecurityLevelTLSv1 Indicates to use only TLSv1. This is the default value.
 */

enum {
	MailDeliverySecurityLevelNone = 0,
	MailDeliverySecurityLevelSSLv3 = 1,
	MailDeliverySecurityLevelTLSv1 = 2,
};

/*!
 @enum AuthenticationScheme
 @discussion Constants the represent the authentication scheme.
 @constant kAuthenticationNone ...
 @constant kAuthenticationPlain AUTH PLAIN.
 @constant kAuthenticationLogin AUTH LOGIN.
 */
enum {
	kAuthenticationNone = 0,
	kAuthenticationPlain = 1, /*Default*/
	kAuthenticationLogin = 2,
};

/*!
 @class TCPConnection
 @abstract Class to connect to a TCP server and to send email messages.
 @discussion Repesents the connection with the server and our client to send the email message.
 */

@interface TCPConnection : NSObject {
@private;
	SSLContextRef _sslContext;
	int _ssocket;
	NSInteger _port;
	NSString *_hostName;
	NSError *_error;
	NSInteger _securityLevel;
	NSTimeInterval _connectionTimeout;
	BOOL _supports8BITMIME;
	BOOL _supportsSTARTTLS;
	BOOL _supportsPlainAuth;
	BOOL _supportsLoginAuth;
	BOOL _uses8BITMIME;
	BOOL _provideDetailedConnectionError;
}

/*!
 @method initWithHost:port:
 @abstract ...
 @discussion if the connection fails, this method returns nil.
 @param hostName
 the name of the host.
 @param portNumber
 the number of port to make the connection.
 */

- (id)initWithHost:(NSString *)hostName port:(NSInteger)portNumber;

/*!
 @method connectionWithHost:port:
 @abstract autoreleased version of @link initWithHost:port: initWithHost:port: @/link.
 */

+ (id)connectionWithHost:(NSString *)hostName port:(NSInteger)portNumber;

/*!
 @method connectToHost:port:
 @abstract attempts to connect to a SMTP server.
 @param hostName
 the name of the host.
 @param portNumber
 the number of port to make the connection.
 */

- (BOOL)connectToHost:(NSString *)hostName port:(NSInteger)portNumber;

/*!
 @method startSSL
 @abstract .
 */

- (BOOL)startSSL;

/*!
 @method invalidate
 @abstract disconnects the reciver from a server.
 */

- (void)invalidate;

/*!
 @method cancelLastRequest
 @abstract cancel last request sent to the server.
 @discussion Used to know when the user canceled the message delivery. This method will invalidate the connection with the server.
 */

- (void)cancelLastRequest;

/*!
 @method write:length:
 @abstract .
 @param buf
 .
 @param len
 .
 */

- (NSInteger)write:(char *)buf length:(NSInteger)len;

/*!
 @method read:length:
 @abstract .
 @param buf
 .
 @param len
 .
 */

- (NSInteger)read:(char *)buf length:(NSInteger)len;

/*!
 @method localIPAddress
 @abstract Used by the framework to say 'Hello' to the remote host, returns the IP Address of this Mac.
 */

+ (NSString *)localIPAddress;

/*!
 @property isValid
 @abstract return <tt>YES</tt> if the reciver is connected to a server.
 */

@property (readonly) BOOL isValid;

/*!
 @property error
 @abstract the output error.
 */

@property (readonly, retain) NSError *error;

/*!
 @property hostName
 @abstract .
 */

@property (readonly, retain) NSString *hostName;

/*!
 @property port
 @abstract .
 */

@property (readonly) NSInteger port;

/*!
 @property uses8BITMIME
 @abstract should use 8 bit data transmission (if possible)?, default is YES. You can turn off this value if you need to send a message in a quoted printable form using SMIME for example.
 */

@property BOOL uses8BITMIME;

/*!
 @property supports8BITMIME
 @abstract returns YES if the relay host supports 8 bit data transmission.
 */

@property (readonly) BOOL supports8BITMIME;

/*!
 @property provideDetailedConnectionError
 @abstract if NO, a generic error will be returned, this only affects to the posible errors at the moment of the connection, note that most of these errors are not good to present to the user, are there only to provide detailed information about when a connection fails. Default if YES, <tt>SMTPMailDelivery</tt> sets this value to NO.
 */

@property BOOL provideDetailedConnectionError;

/*!
 @property securityLevel
 @abstract MailDeliverySecurityLevel, default is <tt>MailDeliverySecurityLevelTLSv1</tt>. Untested.
 */

@property NSInteger securityLevel;

/*!
 @property connectionTimeout
 @abstract conection timeout, default is 60 seconds. <tt>SMTPMailDelivery</tt> set this value to 8 seconds.
 */

@property NSTimeInterval connectionTimeout;

@end

/*!
 @category TCPConnection(SMTPStandardAdditions)
 @abstract .
 */

@interface TCPConnection(SMTPStandardAdditions)

/*!
 @method autenthicateWithHost:userName:password:scheme:
 @abstract authenticates with a server.
 @param hostName
 the name of the host. E.g. smtp.mac.com.
 @param userName
 the username.
 @param password
 the password.
 @param authenticationScheme
 the authentication scheme to use. <tt>kAuthenticationPassword</tt> or <tt>kAuthenticationNone</tt>.
 */

- (BOOL)autenthicateWithHost:(NSString *)hostName userName:(NSString *)userName password:(NSString *)password scheme:(NSInteger)authenticationScheme;

/*!
 @method writeEnvelopeTo:from:
 @abstract write the message envelope.
 @param recipients
 @textblock a CRLF separated list of addresses using the format \@"RCPT TO:<email>. @/textblock See @link //maildelivery_ref/occ/instm/NSArray(NSArrayMailDeliveryAdditions)/componentsJoinedAsRecipients componentsJoinedAsRecipients @/link.
 @param senderAddress
 who sends the message.
 */

- (BOOL)writeEnvelopeTo:(NSString *)recipients from:(NSString *)senderAddress;

/*!
 @method writeData:
 @abstract sends the source of the message.
 @param source
 the raw source of the message. End with CRLF.CRLF (\@"\r\n.\r\n").
 */

- (BOOL)writeData:(NSString *)source;

@end
